--[[
  class: Game.Player

  Player entity class.

  Inherit from <Game.Entity> base class::
]]


--[[
  str: name

  The player's nickname on scoreboard.

  Data Type: string::
  Access: Read-Only::
]]
Game.Player.name


--[[
  int: death

  The player's death count(s).

  Data Type: int::
  Access: Read-Only::
]]
Game.Player.death


--[[
  int: team

  The player's team.

  Data Type: int / <Game.TEAM>::
  Access: Read-Write::
]]
Game.Player.team


--[[
  int: coin

  The player's studio coin count(s).

  Data Type: int::
  Range: 0 ~ 1000000000::
  Access: Read-Write::
]]
Game.Player.coin


--[[
  int: model

  The player's class model.

  Data Type: int / <Game.MODEL>::
  Access: Read-Write::

  Warnings:
    - When changing to any zombie models, all weapons are stripped, given zombie claw, and disabled weapon pickups.
]]
Game.Player.model


--[[
  number: flinch

  The player's painshock/velocity slowdown power multiplier.

  Data Type: number::
  Range: 0.0 ~ 1.0::
  Default: 1.0::
  Access: Read-Write::

  Notes:
    - Higher means more power.
    - Multiplies with attacker's current <Game.Weapon.flinch> power.
]]
Game.Player.flinch


--[[
  number: knockback

  The player's knockback power multiplier.

  Data Type: number::
  Range: 0.0 ~ 3.0::
  Default: 1.0::
  Access: Read-Write::

  Notes:
    - Higher means more power.
    - Multiplies with attacker's current <Game.Weapon.knockback> power.
]]
Game.Player.knockback


--[[
  number: maxspeed

  The player's movement speed multiplier.

  Data Type: number::
  Range: 0.0 ~ 10.0::
  Default: 1.0::
  Access: Read-Write::

  Notes:
    - Higher means faster.
    - Multiplies with current <Game.Weapon.speed> power.
    - The result = Default maxspeed (250) * <Game.Weapon.speed> * this.

  Warnings:
    - The result will be clamped to `sv_maxspeed` server CVar.
]]
Game.Player.maxspeed


--[[
  number: gravity

  The player's gravity multiplier.

  Data Type: number::
  Range: 0.0 ~ 10.0::
  Default: 1.0::
  Access: Read-Write::

  Notes:
    - Higher means heavier.
    - Multiplies with current player's gravity power set from Gravity Modifier block.
    - The result = sv_gravity * Gravity Modifier block (if any) * this.

  Warnings:
    - The result will be clamped to `sv_gravity` server CVar.
]]
Game.Player.gravity


--[[
  bool: infiniteclip

  Enable/disable player's weapon infinite clip/ammo.

  Data Type: bool::
  Access: Read-Write::

  Notes:
    - Incomplete documentation in official website.
    - Applies to all not-configured <Common.WEAPON> weapons.
    - Similar to trancendence-grade weapons in Zombie Scenario.

  Options:
    true  - Enabled.
    false - Disabled.
]]
Game.Player.infiniteclip


--[[
  method: Create

  Get the player entity instance with given entity index.

  Access: Read-Only::

  Parameters:
    index - (*int*) The given entity index (Range: 1 ~ Maximum player slot(s) (`sv_maxplayers` server CVar)).

  Returns:
    (*<Game.Player> / nil*) The player entity instance (nil = Invalid entity index).
]]
function Game.Player.Create (index)


--[[
  method: Respawn

  Force-respawn the player.

  Access: Read-Only::

  Notes:
    - Moves alive player to available active spawn point(s).
]]
function Game.Player:Respawn ()


--[[
  method: Kill

  Kill the player.

  Access: Read-Only::
]]
function Game.Player:Kill ()


--[[
  method: Win

  End current game round and set this player as winner.

  Access: Read-Only::

  Parameters:
    exit - (*bool / nil*) End the game on the next round (true = Enable)(false = Disable)(nil = true).
]]
function Game.Player:Win (exit)


--[[
  method: ShowBuymenu

  Display the weapon selection menu.

  Access: Read-Only::

  Notes:
    - Obeys <Common.UseScenarioBuymenu> setting.
]]
function Game.Player:ShowBuymenu ()


--[[
  method: RemoveWeapon

  Strip all player's weapons.

  Access: Read-Only::
]]
function Game.Player:RemoveWeapon ()


--[[
  method: SetGameSave

  Store the data into player's gamesave space with given identity name.

  Please refer to <GameSave API> topic for more details.

  Access: Read-Only::

  Warnings:
    - The current map MUST support game-save feature.

  Parameters:
    name  - (*string*) The identity of the data.
    value - (*number / string / bool*) The data to store.

   See Also:
    - <Game.Rule.CanSave>
    - <Game.Rule.SetGameSave>
]]
function Game.Player:SetGameSave (name, value)


--[[
  method: GetGameSave

  Retrieve the data from player's gamesave space with given identity name.

  Please refer to <GameSave API> topic for more details.

  Access: Read-Only::

  Warnings:
    - The current map MUST support game-save feature.

  Parameters:
    name  - (*string*) The identity of the data.

  Returns:
    (*number / string / bool / nil*) The retrieved data (nil = No data).

   See Also:
    - <Game.Rule.CanSave>
    - <Game.Rule.GetGameSave>
]]
function Game.Player:GetGameSave (name)


--[[
  method: SetFirstPersonView

  Change the player's view camera perspective to first-person mode.

  Access: Read-Only::
]]
function Game.Player:SetFirstPersonView ()


--[[
  method: SetThirdPersonView

  Change the player's view camera perspective to third-person mode.

  Access: Read-Only::

  Notes:
    - Zoom in & out the camera with mouse scroll.

  Parameters:
    minDist  - (*number*) Minimum camera zoom distance.
    maxDist  - (*number*) Maximum camera zoom distance.
]]
function Game.Player:SetThirdPersonView (minDist, maxDist)


--[[
  method: SetThirdPersonFixedView

  Change the player's view camera perspective to third-person mode and lock its view angles.

  Access: Read-Only::

  Notes:
    - Zoom in & out the camera with mouse scroll.
    - Aim the weapon with mouse pointer.
    - Activates weapons zoom function will raise the camera height instead.
    - Projectile-based weapons will be adjusted automatically to hit the aim position.

  Parameters:
    yaw      - (*number*) The camera yaw rotation degree.
    pitch    - (*number*) The camera pitch rotation degree.
    minDist  - (*number*) Minimum camera zoom distance.
    maxDist  - (*number*) Maximum camera zoom distance.
]]
function Game.Player:SetThirdPersonFixedView (yaw, pitch, minDist, maxDist)


--[[
  method: SetThirdPersonFixedPlane

  Change the raycast setting of player's mouse pointer.

  Access: Read-Only::

  Warnings:
    - <Game.Player.SetThirdPersonFixedView> is REQUIRED to be enabled.

  Parameters:
    plane - (*int / <Game.THIRDPERSON_FIXED_PLANE>*) The raycast setting.

  Recommended setting based on camera view side::
    Top-view   - <Game.THIRDPERSON_FIXED_PLANE.GROUND> or <Game.THIRDPERSON_FIXED_PLANE.XY>.
    Front-view - <Game.THIRDPERSON_FIXED_PLANE.XZ> or <Game.THIRDPERSON_FIXED_PLANE.YZ>.
]]
function Game.Player:SetThirdPersonFixedPlane (plane)


--[[
  func: Signal

  Send an integer value to this player.

  Access: Read-Only::

  Notes:
    - This will raising <UI.Event.OnSignal> event upon receiving the signal.

  Parameters:
    signal - (*8-bit unsigned int*) The value to send (Range: 0 ~ 255).
]]
function Game.Player:Signal (signal)


--[[
  func: SetLevelUI

  Change the display of level & exp bar UI on this player screen.

  Access: Read-Only::

  Warnings:
    - Default UI will be replaced to Zombie-Scenario UI.

  Parameters:
    level   - (*int*) The level.
    expRate - (*number*) The exp bar progress rate (Range: 0.0 ~ 1.0).
]]
function Game.Player:SetLevelUI (level, expRate)


--[[
  func: SetBuymenuLockedUI

  Set the weapon purchase lock state for given weapon.

  Access: Read-Only::

  Parameters:
    weaponid - (*int / <Common.WEAPON>*) The weapon ID.
    uiLocked - (*bool*) Lock this weapon from being selected (true = Enable)(false = Disable).
    level    - (*int / nil*) The level requirement to display (nil = Don't display).
]]
function Game.Player:SetBuymenuLockedUI (weaponid, uiLocked, level)


--[[
  func: SetWeaponInvenLockedUI

  Set the weapon inventory lock state for given weapon.

  Access: Read-Only::

  Warnings:
    - <Common.UseWeaponInven> is REQUIRED to be enabled.

  Parameters:
    weapon   - (*<Game.Weapon>*) The weapon entity instance.
    uiLocked - (*bool*) Lock this weapon from being selected (true = Enable)(false = Disable).
    level    - (*int / nil*) The level requirement to display (nil = Don't display).
]]
function Game.Player:SetWeaponInvenLockedUI (weapon, uiLocked, level)


--[[
  method: GetPrimaryWeapon

  Get the weapon entity instance on primary weapon slot.

  Access: Read-Only::

  Returns:
    (*<Game.Weapon> / nil*) The weapon entity instance (nil = Doesn't have primary weapon or non-scriptable weapon).
]]
function Game.Player:GetPrimaryWeapon ()


--[[
  method: GetSecondaryWeapon

  Get the weapon entity instance on secondary weapon slot.

  Access: Read-Only::

  Returns:
    (*<Game.Weapon> / nil*) The weapon entity instance (nil = Doesn't have secondary weapon or non-scriptable weapon).
]]
function Game.Player:GetSecondaryWeapon ()


--[[
  method: ShowWeaponInven

  Display the weapon inventory menu.

  Access: Read-Only::

  Warnings:
    - <Common.UseWeaponInven> is REQUIRED to be enabled.
]]
function Game.Player:ShowWeaponInven ()


--[[
  method: ToggleWeaponInven

  Toggle the display of weapon inventory menu.

  Access: Read-Only::

  Warnings:
    - <Common.UseWeaponInven> is REQUIRED to be enabled.
]]
function Game.Player:ToggleWeaponInven ()


--[[
  method: GetWeaponInvenList

  Get the player's weapon inventory list.

  Access: Read-Only::

  Notes:
    - Current equipped weapons are not included.

  Warnings:
    - <Common.UseWeaponInven> is REQUIRED to be enabled.

  Returns:
    (*table / <~Virtual Table.weaponList>*) The weapon list.
]]
function Game.Player:GetWeaponInvenList ()


--[[
  method: ClearWeaponInven

  Clear the player's weapon inventory list.

  Access: Read-Only::

  Notes:
    - Undocumented in official website.

  Warnings:
    - <Common.UseWeaponInven> is REQUIRED to be enabled.
    - Affects player's gamesave data if enabled.
]]
function Game.Player:ClearWeaponInven ()


--[[
  event: OnJoiningSpawn

  --- Lua
  function Game.Player:OnJoiningSpawn ()
  ---

  Called when this player is spawned for the first time.

  Access: Write-Only::

  Notes:
    - Undocumented in official website.
]]


--[[
  event: OnSpawn

  --- Lua
  function Game.Player:OnSpawn ()
  ---

  Called when this player is (re)spawned.

  Access: Write-Only::
]]


--[[
  event: OnKilled

  --- Lua
  function Game.Player:OnKilled (killer, weapontype, hitbox)
  ---

  Called when this player is killed.

  Access: Write-Only::

  Notes:
    - Incomplete documentation in official website.

  Parameters:
    killer     - (*<Game.Player> / nil*) The killer entity (nil = Is not a player).
    weapontype - (*int / <Game.WEAPONTYPE>*) The killer's weapon's category.
    hitbox     - (*int / <Game.HITBOX>*) The victim hitbox got hit.
]]


--[[
  event: OnAssist

  --- Lua
  function Game.Player:OnAssist (victim, killer)
  ---

  Called when this player assited the killer on killing an enemy.

  Access: Write-Only::

  Parameters:
    victim - (*<Game.Player>*) The victim entity.
    killer - (*<Game.Player> / nil*) The killer entity (nil = Is not a player).
]]

